蓝牙中央设备管理器 PRO#

BluetoothCentralManager 提供了用于操作 BLE 中央设备的核心接口，包括扫描附近蓝牙设备、连接外设、获取已知设备、断开连接等能力。适用于实现如外设控制、数据采集、IoT通信等典型蓝牙场景。

成员属性#

isScanning: Promise<boolean>#

获取当前是否正在扫描外围设备。

• 类型：Promise<boolean>

• 示例：

  1const scanning = await BluetoothCentralManager.isScanning
  2console.log(scanning ? "正在扫描" : "未扫描")

方法#

startScan(onDiscoverPeripheral, options?): Promise<void>#

启动 BLE 设备扫描，直到调用 stopScan() 结束。每发现一个设备都会触发 onDiscoverPeripheral 回调。

参数#

• onDiscoverPeripheral: (peripheral, advertisementData, rssi) => void

  • 每发现一个外围设备时调用

  • 参数说明：

    • peripheral: BluetoothPeripheral 外设对象
    • advertisementData: BluetoothAdvertisementData 广播数据
    • rssi: number 信号强度（dBm）

• options?: { services?: string[]; allowDuplicates?: boolean; solicitedServiceUUIDs?: string[] }

  • services: 只扫描包含指定服务 UUID 的外设
  • allowDuplicates: 是否允许重复回调同一设备，默认 false
  • solicitedServiceUUIDs: 一个包含外设请求的服务 UUID 的数组，表明希望由中央设备提供哪些服务

BluetoothAdvertisementData 广播数据结构#

在使用 BluetoothCentralManager.startScan() 进行蓝牙扫描时，每次发现设备都会返回包含该设备广播数据的 advertisementData 对象。该对象包含设备在广播包中附带的多种信息字段，用于识别、过滤、分类外设。

数据结构说明#

1type BluetoothAdvertisementData = {
2  localName?: string
3  txPowerLevel?: number
4  manufacturerData?: Data
5  serviceData?: Record<string, Data>
6  serviceUUIDs?: string[]
7  overflowServiceUUIDs?: string[]
8  isConnectable?: boolean
9  solicitedServiceUUIDs?: string[]
10}

字段详解#

常见用途#

• 根据 localName 或 serviceUUIDs 进行设备筛选
• 解析 manufacturerData 判断厂商/设备类型
• 结合 txPowerLevel 和 RSSI 估算设备距离
• 利用 isConnectable 判断是否需要尝试连接

注意事项#

• 所有字段均为可选项，某些设备可能不广播特定字段
• manufacturerData 和 serviceData 是原始二进制数据（Data 类型），需根据厂商协议解析
• serviceUUIDs 仅代表广播包中声明的服务，完整服务需通过 discoverServices() 获取

返回值#

• Promise<void>：扫描启动成功时 resolve，失败时 reject

示例#

1await BluetoothCentralManager.startScan((peripheral, adv, rssi) => {
2  console.log(`发现设备: ${peripheral.name}, 信号: ${rssi} dBm`)
3}, {
4  services: ["180D"], // 只扫描支持心率服务的设备
5  allowDuplicates: false
6})

stopScan(): Promise<void>#

停止正在进行的扫描操作。

返回值#

• Promise<void>：成功停止时 resolve

示例#

1await BluetoothCentralManager.stopScan()
2console.log("已停止扫描")

retrievePeripherals(ids: string[]): Promise<BluetoothPeripheral[]>#

根据设备 UUID 获取已知的蓝牙设备（可能已连接或已配对）。

参数#

• ids: string[]：设备的唯一标识符数组

返回值#

• Promise<BluetoothPeripheral[]>：返回符合 ID 的设备列表

示例#

1const knownDevices = await BluetoothCentralManager.retrievePeripherals(["A1-B2-C3-D4"])

retrieveConnectedPeripherals(serviceUUIDs: string[]): Promise<BluetoothPeripheral[]>#

获取当前连接中并提供指定服务的外围设备。

参数#

• serviceUUIDs: string[]：过滤条件，仅返回包含这些服务 UUID 的设备

返回值#

• Promise<BluetoothPeripheral[]>：匹配的设备列表

示例#

1const connected = await BluetoothCentralManager.retrieveConnectedPeripherals(["180F"])
2console.log(`发现 ${connected.length} 个已连接电池服务设备`)

connect(peripheral, options?): Promise<void>#

与指定外围设备建立连接。

参数#

• peripheral: BluetoothPeripheral：要连接的设备

• options?: 可选连接配置：

  • startDelay?: number：延迟连接（秒）
  • enableTransportBridging?: boolean：启用传输桥接（用于特殊外设）
  • requiresANCS?: boolean：是否需要 ANCS 支持（苹果通知服务）
  • enableAutoReconnect?: boolean：是否自动重连
  • notifyOnConnection?: boolean - 是否通知app连接成功
  • notifyOnDisconnection?: boolean - 是否通知app连接已断开
  • notifyOnNotification?: boolean - 是否通知app收到通知

返回值#

• Promise<void>：连接成功 resolve，失败 reject

示例#

1await BluetoothCentralManager.connect(peripheral, {
2  startDelay: 100,
3  enableAutoReconnect: true
4})
5console.log("已连接到外设")

disconnect(peripheral): Promise<void>#

断开与指定外围设备的连接。此操作是非阻塞的，部分尚未完成的操作可能无法继续。

参数#

• peripheral: BluetoothPeripheral：要断开的设备

返回值#

• Promise<void>

注意事项#

• 并不能保证物理连接立即断开（系统层面可能仍被其他 App 占用）
• 但从 Scripting 角度来看，设备即视为断开，onDisconnected 回调将被调用

示例#

1await BluetoothCentralManager.disconnect(peripheral)
2console.log("已断开连接")

注意事项#

• 所有蓝牙方法需要在已授权蓝牙权限的前提下执行。
• 设备连接后请调用 discoverServices() 发现服务，然后通过 discoverCharacteristics() 获取特征值后再读写。
• 建议在扫描结束后手动调用 stopScan()，避免后台持续运行。

示例工作流程#

1await BluetoothCentralManager.startScan((peripheral) => {
2  BluetoothCentralManager.stopScan()
3  BluetoothCentralManager.connect(peripheral)
4    .then(() => peripheral.discoverServices())
5    .then(() => console.log("服务已发现"))
6})